Non-Payment Authentication (NPA)

La Non-Payment Authentication (NPA) è un flusso di autenticazione 3D Secure 2 (3DS2) che consente al merchant di verificare il titolare della carta e salvare i dati senza effettuare alcun addebito.

A differenza di un pagamento tradizionale, in cui l’autenticazione 3DS e la transazione finanziaria avvengono contestualmente, con NPA il processo si limita alla sola fase di autenticazione.
Il risultato è un token di carta autenticato che è possibile utilizzare per successive transazioni (ad esempio pagamenti ricorrenti o one‑click).

Non-Payment Authentication

Quando usare NPA

NPA è indicato nei seguenti scenari:

Tokenizzazione della carta in fase di registrazione, prima di un acquisto
Verifica del titolare della carta senza richiedere un pagamento

NPA non addebita importi

Il flusso NPA non genera alcun movimento finanziario.
Per effettuare un pagamento è necessario avviare una nuova transazione.

Configurazione backoffice

Per ricevere i dettagli dell’autenticazione 3DS al termine della transazione, è necessario abilitare il campo ThreeDS nel backoffice Gestpay.
In assenza di questa configurazione, le transazioni NPA funzioneranno correttamente ma non restituiranno le informazioni 3DS.

Percorso di configurazione: Pagina Pagamento → Campi & Parametri → ThreeDS

Impostazioni disponibili:

No Display → integrazioni che non utilizzano la pagina di pagamento Fabrick
Payment Page → integrazioni che utilizzano la pagina di pagamento Fabrick

Non-Payment Authentication

Per tutte e due le configurazioni è necessario abilitare il campo threeDS nella sezione Campi & Parametri.

Flusso di integrazione

Il flusso NPA è supportato da tutte le tipologie di integrazione offerte da Fabrick.

Integrazioni supportate

✓HPPO

✓Pay By Link

✓Lightbox

✓API Only

Inizializzazione della richiesta NPA

Per avviare un flusso NPA è necessario effettuare, lato server, una chiamata payment/create impostando i seguenti parametri:

amount con importo 0 per non addebitare nessun importo.
transDetails.type con NPA per indicandare la sistema di processare la transazione come sola autenticazione
paymentType con ["CREDITCARD"] per indicare al sistema di presentare solo il form carta sulla pagina di pagamento.
requestToken valorizzato con MASKEDPAN.

pagina di pagamento

Il parametro paymentType non è necessario nelle integrazioni API Only, dove il form carta è gestito direttamente dal merchant.

token

Il parametro requestToken consente di ottenere un token della carta autenticata da utilizzare per transazioni future.
Vedi Tokenizzazione.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

{
  "shopLogin": "GESPAY12345",
  "amount": "0", //nessun addebito
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID",
  "paymentType": ["CREDITCARD"], //presentare pagina di inserimento dati carta
  "requestToken": "MASKEDPAN", //richiesta token della carta
  "transDetails": {
    "type": "NPA" //transazione di sola autenticazione
  }
}

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "paymentToken": "d3026f8c-88e3-4862-a962-c0fa29e0f266",
    "paymentID": "2423879934511",
    "userRedirect": null,
    "qrCode": null
  }
}

Processo autenticazione 3DS

Per tutte le integrazioni hosted, la fase di autenticazione è gestita direttamente da Fabrick.

Nelle integrazioni API Only il merchant deve gestire manualmente la fase di autenticazione effettuando il redirect del buyer verso l’URL restituito dopo l’invio dei dati carta.

Dopo l’invio dei dati carta, il sistema restituisce l’errore 8006 nel campo payload.transactionErrorCode, che indica la necessità di completare l’autenticazione del buyer.

L’URL di autenticazione è disponibile nel campo payload.userRedirect.href.

Dettaglio transazione

Al termine del flusso, Fabrick restituisce l’esito dell’autenticazione e il token della carta.

Per maggiori dettagli consulta la sezione Dettaglio transazione e Notifica del Pagamento della specifica integrazione utilizzata

Per verificare il dettaglio completo dell’autenticazione è possibile utilizzare l’endpoint GET payment/detail, passando il paymentID.

Request

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "detail",
        "transactionResult": "AUTHENTICATED",
        "transactionState": "",
        "transactionErrorCode": "",
        "transactionErrorDescription": "",
        "bankTransactionID": "1318",
        "shopTransactionID": "",
        "shopTransactionID_2": "",
        "authorizationCode": "",
        "paymentID": "",
        "currency": "",
        "country": "",
        "company": "",
        "tdLevel": "",
        "threeDS": {
            "authenticationResult": {
                "authenticationLevel": "2C",
                "authenticationStatus": "Y",
                "authStatusReason": "",
                "challengeResultTransStatus": "",
                "XID": "87dc52d7-a059-4afa-8763-bf4a86e3ede9",
                "AV": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
                "ECI": "05",
                "AVAlgorithm": "",
                "threeDsVersion": "2.1.0"
            },
            "transDetails": {
                "authData": "",
                "authMethod": "02",
                "authTimeStamp": "202504281041",
                "acsID": "bc7007fe-45fc-471d-999e-d6111951999e"
            }
        },
        "events": null,
        "buyer": null,
        "risk": null,
        "customInfo": null,
        "alertCode": "",
        "alertDescription": "",
        "cvvPresent": "",
        "dcc": null,
        "maskedPAN": "",
        "paymentMethod": "",
        "productType": "",
        "token": "40G5KMXUQQ613101",
        "tokenExpiryMonth": "05",
        "tokenExpiryYear": "27",
        "tokenDetails": {
            "TokenValue": "40G5KMXUQQ613101",
            "TokenExpiryMonth": "05",
            "TokenExpiryYear": "27",
            "TokenProvider": "AXERVE",
            "CardDetails": {
                "CardSuffix": "3101",
                "CardExpiryMonth": "05",
                "CardExpiryYear": "27",
                "CardHolderName": null
            },
            "CardAssets": {
                "CardArt": {
                    "Type": null,
                    "MediaContents": null,
                    "Height": null,
                    "Width": null
                },
                "BrandLogo": {
                    "Type": null,
                    "MediaContents": null,
                    "Height": null,
                    "Width": null
                }
            }
        },
        "fraudPrevention": null,
        "automaticOperation": null
    }
}

Nella risposta, i campi rilevanti per un flusso NPA sono:

Campo	Descrizione
`transactionResult`	Esito dell'autenticazione: `AUTHENTICATED` / `DECLINED`
`threeDS.authenticationResult.authenticationLevel`	Livello di autenticazione 3DS
`threeDS.authenticationResult.authenticationStatus`	Stato dell’autenticazione
`threeDS.authenticationResult.authStatusReason`	Codice motivo dell’esito
`threeDS.authenticationResult.ECI`	Electronic Commerce Indicator, valorizzato solo in caso di esito positivo
`tokenDetails.TokenValue`	Token della carta
`tokenDetails.TokenExpiryMonth` / `tokenDetails.TokenExpiryYear`	Scadenza del token

Gestione esiti negativi in NPA

Le transazioni NPA con esito negativo riportano transactionResult: "DECLINED" e valorizzano il dettaglio dell’errore nei campi authenticationStatus e authStatusReason.

Dettaglio autenticazione e gestione errori

authenticationLevel

Il campo authenticationLevel indica il tipo di flusso di autenticazione 3DS applicato alla transazione

Valore	Descrizione
`1H`	3DS 1.0 half — Autenticazione 3DS 1.0 parziale.
`1F`	3DS 1.0 full — Autenticazione 3DS 1.0 completa.
`2F`	3DS 2.0 frictionless — Autenticazione 3DS 2.0 senza interazione del buyer.
`2C`	3DS 2.0 challenge — Autenticazione 3DS 2.0 con challenge completata dal buyer.
`2E`	3DS 2.0 exemption — Autenticazione 3DS 2.0 con esenzione applicata.
`OL`	One leg — Transazione processata come one leg, autenticazione non richiesta.
`TR`	TRA esterna — Transazione processata come TRA (Transaction Risk Analysis) esterna.
`NA`	No authentication — Nessuna autenticazione eseguita.

authenticationStatus

Il campo authenticationStatus indica l’esito dell’autenticazione.

Valore	Descrizione
`Y`	Frictionless — l’issuer ha autenticato con successo il buyer senza richiedere alcuna interazione esplicita. L’autenticazione è considerata completata positivamente e la transazione può proseguire.
`C`	Challenge — l’issuer richiede la verifica del buyer. Il buyer deve completare l’autenticazione tramite la challenge, utilizzando l’URL fornito nel campo `payload.userRedirect.href`. L’esito della transazione dipenderà dal risultato della challenge.
`N`	Not Authenticated — l’issuer decide di non concedere l’autenticazione del buyer sulla base delle proprie valutazioni di rischio. In questo scenario la fase di challenge non viene avviata, in quanto l’autenticazione non è autorizzata dall’issuer. La transazione termina quindi con esito negativo.
`U`	Authentication Could Not Be Performed — l’autenticazione non può essere eseguita a causa di un errore tecnico presso il Directory Server (DS) o l’Access Control Server (ACS). Dal punto di vista del flusso transazionale, l’esito viene gestito come `N`.
`A`	Attempted to Authenticate — l’autenticazione è stata tentata, ma non completata (ad esempio per limiti tecnici o di canale), pur consentendo di procedere. L’esito viene trattato come `Y` ai fini del flusso e della liability.
`R`	Rejected — l’issuer rifiuta esplicitamente la richiesta di autenticazione. L’autenticazione non viene completata e l’esito è gestito come `N`, con conseguente esito negativo della transazione.

authStatusReason

Il campo authStatusReason specifica il motivo dell’esito restituito dall’issuer o dall’ACS. In caso di authenticationStatus: N o U, questo campo fornisce un codice numerico che identifica la causa specifica del rifiuto o dell’impossibilità di autenticare.

Codice	Descrizione
`01`	Card authentication failed
`02`	Unknown Device
`03`	Unsupported Device
`04`	Exceeds authentication frequency limit
`05`	Expired card
`06`	Invalid card number
`07`	Invalid transaction
`08`	No Card record
`09`	Security failure
`10`	Stolen card
`11`	Suspected fraud
`12`	Transaction not permitted to cardholder
`13`	Cardholder not enrolled in service
`14`	Transaction timed out at the ACS
`15`	Low confidence
`16`	Medium confidence
`17`	High confidence
`18`	Very High confidence
`19`	Exceeds ACS maximum challenges
`20`	Non-Payment transaction not supported
`21`	3RI transaction not supported
`22`	ACS technical issue
`23`	Decoupled Authentication required by ACS but not requested by 3DS Requestor
`24`	3DS Requestor Decoupled Max Expiry Time exceeded
`25`	Decoupled Authentication was provided insufficient time to authenticate cardholder
`26`	Authentication attempted but not performed by the cardholder
`27`	Preferred authentication method not supported
`28–79`	Riservati per uso futuro EMVCo (valori non validi fino a definizione EMVCo)
`80–99`	Riservati per uso del Directory Server (DS)

Di seguito un esempio di risposta payment/detail con esito negativo DECLINED, in cui transactionErrorCode e transactionErrorDescription risultano vuoti e la causa dell'errore è leggibile tramite authenticationStatus e authStatusReason:

Request

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "transactionType": "detail",
    "transactionResult": "DECLINED",
    "transactionState": "",
    "transactionErrorCode": "",
    "transactionErrorDescription": "",
    "threeDS": {
      "authenticationResult": {
        "authenticationLevel": "2C",
        "authenticationStatus": "N",
        "authStatusReason": "19",
        "XID": "29797f4c-52c7-404e-8ce5-6e17d946e38d",
        "AV": "",
        "ECI": null,
        "threeDsVersion": "2.1.0"
      },
      "transDetails": {
        "authMethod": "02",
        "authTimeStamp": "202504281129",
        "acsID": "96be2efb-3f2d-49c5-93f5-c8d7e9ec0107"
      }
    },
    "token": "40G5KMXUQQ613101",
    "tokenExpiryMonth": "05",
    "tokenExpiryYear": "27"
  }
}

In questo esempio authenticationLevel: "2C" indica che per la transazione è stato richiesto il flusso 3DS2 con challenge, questo valore descrive il tipo di flusso e non l’esito dell’autenticazione.

authenticationStatus: "N" indica che l’autenticazione è stata negata, mentre authStatusReason: "19" specifica la causa "Exceeds ACS maximum challenges" — il numero massimo di challenge consentiti dall’ACS è stato superato.

Configurazione backoffice​

Flusso di integrazione​

Integrazioni supportate

Inizializzazione della richiesta NPA​

Processo autenticazione 3DS​

Dettaglio transazione​

Dettaglio autenticazione e gestione errori​

authenticationLevel​

authenticationStatus​

authStatusReason​

Configurazione backoffice

Flusso di integrazione

Inizializzazione della richiesta NPA

Processo autenticazione 3DS

Dettaglio transazione

Dettaglio autenticazione e gestione errori

authenticationLevel

authenticationStatus

authStatusReason